<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Executing Applications: exo Reference Manual</title>
<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot">
<link rel="home" href="index.html" title="exo Reference Manual">
<link rel="up" href="exo-miscelleanous.html" title="Part VI. Miscelleanous">
<link rel="prev" href="exo-Binding-Properties-Functions.html" title="Binding Properties Functions">
<link rel="next" href="exo-String-Utility-Functions.html" title="String Utility Functions">
<meta name="generator" content="GTK-Doc V1.33.1 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle">
<td width="100%" align="left" class="shortcuts">
<a href="#" class="shortcut">Top</a><span id="nav_description">  <span class="dim">|</span> 
                  <a href="#exo-Executing-Applications.description" class="shortcut">Description</a></span>
</td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
<td><a accesskey="u" href="exo-miscelleanous.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
<td><a accesskey="p" href="exo-Binding-Properties-Functions.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
<td><a accesskey="n" href="exo-String-Utility-Functions.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
</tr></table>
<div class="refentry">
<a name="exo-Executing-Applications"></a><div class="titlepage"></div>
<div class="refnamediv"><table width="100%"><tr>
<td valign="top">
<h2><span class="refentrytitle"><a name="exo-Executing-Applications.top_of_page"></a>Executing Applications</span></h2>
<p>Executing Applications — Execute preferred applications</p>
</td>
<td class="gallery_image" valign="top" align="right"></td>
</tr></table></div>
<div class="refsect1">
<a name="exo-Executing-Applications.functions"></a><h2>Functions</h2>
<div class="informaltable"><table class="informaltable" width="100%" border="0">
<colgroup>
<col width="150px" class="functions_proto_type">
<col class="functions_proto_name">
</colgroup>
<tbody>
<tr>
<td class="function_type">
<span class="returnvalue">gboolean</span>
</td>
<td class="function_name">
<a class="link" href="exo-Executing-Applications.html#exo-execute-preferred-application" title="exo_execute_preferred_application ()">exo_execute_preferred_application</a> <span class="c_punctuation">()</span>
</td>
</tr>
<tr>
<td class="function_type">
<span class="returnvalue">gboolean</span>
</td>
<td class="function_name">
<a class="link" href="exo-Executing-Applications.html#exo-execute-preferred-application-on-screen" title="exo_execute_preferred_application_on_screen ()">exo_execute_preferred_application_on_screen</a> <span class="c_punctuation">()</span>
</td>
</tr>
<tr>
<td class="function_type">
<span class="returnvalue">gboolean</span>
</td>
<td class="function_name">
<a class="link" href="exo-Executing-Applications.html#exo-execute-terminal-shell" title="exo_execute_terminal_shell ()">exo_execute_terminal_shell</a> <span class="c_punctuation">()</span>
</td>
</tr>
<tr>
<td class="function_type">
<span class="returnvalue">gboolean</span>
</td>
<td class="function_name">
<a class="link" href="exo-Executing-Applications.html#exo-execute-terminal-shell-on-screen" title="exo_execute_terminal_shell_on_screen ()">exo_execute_terminal_shell_on_screen</a> <span class="c_punctuation">()</span>
</td>
</tr>
</tbody>
</table></div>
</div>
<div class="refsect1">
<a name="exo-Executing-Applications.includes"></a><h2>Includes</h2>
<pre class="synopsis">#include &lt;exo/exo.h&gt;
</pre>
</div>
<div class="refsect1">
<a name="exo-Executing-Applications.description"></a><h2>Description</h2>
<p>This module provides functions to execute certain kinds of applications,
for which users can select their preferred ones. For example, whenever
you need to run a command in a terminal emulator from within your
application you should use <a class="link" href="exo-Executing-Applications.html#exo-execute-terminal-shell" title="exo_execute_terminal_shell ()"><code class="function">exo_execute_terminal_shell()</code></a> or
<a class="link" href="exo-Executing-Applications.html#exo-execute-terminal-shell-on-screen" title="exo_execute_terminal_shell_on_screen ()"><code class="function">exo_execute_terminal_shell_on_screen()</code></a> to make sure you run the user's
preferred terminal emulator.
On the other hand if you need to display an URL (i.e. you want to point
the user to the website of your application), you should use <code class="function">gtk_show_uri()</code>
instead, as it will try to automatically determine the appropriate
viewer for a given URI.</p>
</div>
<div class="refsect1">
<a name="exo-Executing-Applications.functions_details"></a><h2>Functions</h2>
<div class="refsect2">
<a name="exo-execute-preferred-application"></a><h3>exo_execute_preferred_application ()</h3>
<pre class="programlisting"><span class="returnvalue">gboolean</span>
exo_execute_preferred_application (<em class="parameter"><code>const <span class="type">gchar</span> *category</code></em>,
                                   <em class="parameter"><code>const <span class="type">gchar</span> *parameter</code></em>,
                                   <em class="parameter"><code>const <span class="type">gchar</span> *working_directory</code></em>,
                                   <em class="parameter"><code><span class="type">gchar</span> **envp</code></em>,
                                   <em class="parameter"><code><span class="type">GError</span> **error</code></em>);</pre>
<p>Convenience wrapper to <a class="link" href="exo-Executing-Applications.html#exo-execute-preferred-application-on-screen" title="exo_execute_preferred_application_on_screen ()"><code class="function">exo_execute_preferred_application_on_screen()</code></a>, which
runs the preferred application for <em class="parameter"><code>category</code></em>
 on the default <span class="type">GdkScreen</span>.</p>
<p>Note that even if this method returns <code class="literal">TRUE</code> there's no warranty that
the preferred application for <em class="parameter"><code>category</code></em>
 was run successfully, because
of the way the helper framework is implemented. But you can be sure
that if the execution fails at a later stage, the library will popup
an error dialog to inform the user that the execution failed.</p>
<div class="refsect3">
<a name="exo-execute-preferred-application.parameters"></a><h4>Parameters</h4>
<div class="informaltable"><table class="informaltable" width="100%" border="0">
<colgroup>
<col width="150px" class="parameters_name">
<col class="parameters_description">
<col width="200px" class="parameters_annotations">
</colgroup>
<tbody>
<tr>
<td class="parameter_name"><p>category</p></td>
<td class="parameter_description"><p>the category of the preferred application to launch.</p></td>
<td class="parameter_annotations"> </td>
</tr>
<tr>
<td class="parameter_name"><p>parameter</p></td>
<td class="parameter_description"><p>additional parameter to pass to the preferred application
(i.e. an URL to pass to the preferred browser) or <code class="literal">NULL</code>
to pass no parameter.</p></td>
<td class="parameter_annotations"> </td>
</tr>
<tr>
<td class="parameter_name"><p>working_directory</p></td>
<td class="parameter_description"><p>path to the directory in which to execute the
preferred application for <em class="parameter"><code>category</code></em>
.</p></td>
<td class="parameter_annotations"> </td>
</tr>
<tr>
<td class="parameter_name"><p>envp</p></td>
<td class="parameter_description"><p>child's environment, or <code class="literal">NULL</code> to inherit parent's.</p></td>
<td class="parameter_annotations"> </td>
</tr>
<tr>
<td class="parameter_name"><p>error</p></td>
<td class="parameter_description"><p>return location for errors or <code class="literal">NULL</code>.</p></td>
<td class="parameter_annotations"> </td>
</tr>
</tbody>
</table></div>
</div>
<div class="refsect3">
<a name="exo-execute-preferred-application.returns"></a><h4>Returns</h4>
<p> <code class="literal">TRUE</code> on success, else <code class="literal">FALSE</code>.</p>
</div>
<p class="since">Since: <a class="link" href="ch01.html#api-index-0.3.1.3" title="Added in 0.3.1.3">0.3.1.3</a></p>
</div>
<hr>
<div class="refsect2">
<a name="exo-execute-preferred-application-on-screen"></a><h3>exo_execute_preferred_application_on_screen ()</h3>
<pre class="programlisting"><span class="returnvalue">gboolean</span>
exo_execute_preferred_application_on_screen
                               (<em class="parameter"><code>const <span class="type">gchar</span> *category</code></em>,
                                <em class="parameter"><code>const <span class="type">gchar</span> *parameter</code></em>,
                                <em class="parameter"><code>const <span class="type">gchar</span> *working_directory</code></em>,
                                <em class="parameter"><code><span class="type">gchar</span> **envp</code></em>,
                                <em class="parameter"><code><span class="type">GdkScreen</span> *screen</code></em>,
                                <em class="parameter"><code><span class="type">GError</span> **error</code></em>);</pre>
<p>Launches the preferred application for the given <em class="parameter"><code>category</code></em>
 with the
<em class="parameter"><code>parameter</code></em>
 on <em class="parameter"><code>screen</code></em>
 in the specified <em class="parameter"><code>working_directory</code></em>
.</p>
<p>libexo currently supports the following categories: %"WebBrowser",
%"MailReader" and %"TerminalEmulator". If you specify an invalid
<em class="parameter"><code>category</code></em>
 here, the execution will fail at a later stage and the
user will be presented with an error dialog.</p>
<p>Note that even if this method returns <code class="literal">TRUE</code> there's no warranty that
the preferred application for <em class="parameter"><code>category</code></em>
 was run successfully, because
of the way the helper framework is implemented. But you can be sure
that if the execution fails at a later stage, the library will popup
an error dialog to inform the user that the execution failed.</p>
<div class="refsect3">
<a name="exo-execute-preferred-application-on-screen.parameters"></a><h4>Parameters</h4>
<div class="informaltable"><table class="informaltable" width="100%" border="0">
<colgroup>
<col width="150px" class="parameters_name">
<col class="parameters_description">
<col width="200px" class="parameters_annotations">
</colgroup>
<tbody>
<tr>
<td class="parameter_name"><p>category</p></td>
<td class="parameter_description"><p>the category of the preferred application to launch.</p></td>
<td class="parameter_annotations"> </td>
</tr>
<tr>
<td class="parameter_name"><p>parameter</p></td>
<td class="parameter_description"><p>additional parameter to pass to the preferred application
(i.e. an URL to pass to the preferred browser) or <code class="literal">NULL</code>
to pass no parameter.</p></td>
<td class="parameter_annotations"> </td>
</tr>
<tr>
<td class="parameter_name"><p>working_directory</p></td>
<td class="parameter_description"><p>path to the directory in which to execute the
preferred application for <em class="parameter"><code>category</code></em>
.</p></td>
<td class="parameter_annotations"> </td>
</tr>
<tr>
<td class="parameter_name"><p>envp</p></td>
<td class="parameter_description"><p>child's environment, or <code class="literal">NULL</code> to inherit parent's.</p></td>
<td class="parameter_annotations"> </td>
</tr>
<tr>
<td class="parameter_name"><p>screen</p></td>
<td class="parameter_description"><p>the <span class="type">GdkScreen</span> on which to run the preferred
application for <em class="parameter"><code>category</code></em>
.</p></td>
<td class="parameter_annotations"> </td>
</tr>
<tr>
<td class="parameter_name"><p>error</p></td>
<td class="parameter_description"><p>return location for errors or <code class="literal">NULL</code>.</p></td>
<td class="parameter_annotations"> </td>
</tr>
</tbody>
</table></div>
</div>
<div class="refsect3">
<a name="exo-execute-preferred-application-on-screen.returns"></a><h4>Returns</h4>
<p> <code class="literal">TRUE</code> on success, else <code class="literal">FALSE</code>.</p>
</div>
<p class="since">Since: <a class="link" href="ch01.html#api-index-0.3.1.3" title="Added in 0.3.1.3">0.3.1.3</a></p>
</div>
<hr>
<div class="refsect2">
<a name="exo-execute-terminal-shell"></a><h3>exo_execute_terminal_shell ()</h3>
<pre class="programlisting"><span class="returnvalue">gboolean</span>
exo_execute_terminal_shell (<em class="parameter"><code>const <span class="type">gchar</span> *command_line</code></em>,
                            <em class="parameter"><code>const <span class="type">gchar</span> *working_directory</code></em>,
                            <em class="parameter"><code><span class="type">gchar</span> **envp</code></em>,
                            <em class="parameter"><code><span class="type">GError</span> **error</code></em>);</pre>
<p>Convenience wrapper to <a class="link" href="exo-Executing-Applications.html#exo-execute-terminal-shell-on-screen" title="exo_execute_terminal_shell_on_screen ()"><code class="function">exo_execute_terminal_shell_on_screen()</code></a>, which
executes the <em class="parameter"><code>command_line</code></em>
 on the default <span class="type">GdkScreen</span>.</p>
<p>Note that even if this method returns <code class="literal">TRUE</code> there's no warranty that
the <em class="parameter"><code>command_line</code></em>
 was run successfully, because of the way the helper
framework is implemented. But you can be sure that if the execution
fails at a later stage, the library will popup an error dialog to
inform the user that the execution failed.</p>
<div class="refsect3">
<a name="exo-execute-terminal-shell.parameters"></a><h4>Parameters</h4>
<div class="informaltable"><table class="informaltable" width="100%" border="0">
<colgroup>
<col width="150px" class="parameters_name">
<col class="parameters_description">
<col width="200px" class="parameters_annotations">
</colgroup>
<tbody>
<tr>
<td class="parameter_name"><p>command_line</p></td>
<td class="parameter_description"><p>shell command line to execute.</p></td>
<td class="parameter_annotations"> </td>
</tr>
<tr>
<td class="parameter_name"><p>working_directory</p></td>
<td class="parameter_description"><p>path to the directory in which to execute <em class="parameter"><code>command_line</code></em>
or <code class="literal">NULL</code> to use the current working directory.</p></td>
<td class="parameter_annotations"> </td>
</tr>
<tr>
<td class="parameter_name"><p>envp</p></td>
<td class="parameter_description"><p>child's environment, or <code class="literal">NULL</code> to inherit parent's.</p></td>
<td class="parameter_annotations"> </td>
</tr>
<tr>
<td class="parameter_name"><p>error</p></td>
<td class="parameter_description"><p>return location for errors or <code class="literal">NULL</code>.</p></td>
<td class="parameter_annotations"> </td>
</tr>
</tbody>
</table></div>
</div>
<div class="refsect3">
<a name="exo-execute-terminal-shell.returns"></a><h4>Returns</h4>
<p> <code class="literal">TRUE</code> on success, else <code class="literal">FALSE</code>.</p>
</div>
<p class="since">Since: <a class="link" href="ch01.html#api-index-0.3.1.3" title="Added in 0.3.1.3">0.3.1.3</a></p>
</div>
<hr>
<div class="refsect2">
<a name="exo-execute-terminal-shell-on-screen"></a><h3>exo_execute_terminal_shell_on_screen ()</h3>
<pre class="programlisting"><span class="returnvalue">gboolean</span>
exo_execute_terminal_shell_on_screen (<em class="parameter"><code>const <span class="type">gchar</span> *command_line</code></em>,
                                      <em class="parameter"><code>const <span class="type">gchar</span> *working_directory</code></em>,
                                      <em class="parameter"><code><span class="type">gchar</span> **envp</code></em>,
                                      <em class="parameter"><code><span class="type">GdkScreen</span> *screen</code></em>,
                                      <em class="parameter"><code><span class="type">GError</span> **error</code></em>);</pre>
<p>Executes <em class="parameter"><code>command_line</code></em>
 in the default terminal emulator on the specified
<em class="parameter"><code>screen</code></em>
.</p>
<p>If no preferred terminal emulator was chosen by the user so far and
no sane fallback could be located, the user will be presented with
the preferred application chooser dialog, which prompts to choose
a default terminal emulator, and the <em class="parameter"><code>command_line</code></em>
 will be run
afterwards using the new default.</p>
<p>Note that even if this method returns <code class="literal">TRUE</code> there's no warranty that
the <em class="parameter"><code>command_line</code></em>
 was run successfully, because of the way the helper
framework is implemented. But you can be sure that if the execution
fails at a later stage, the library will popup an error dialog to
inform the user that the execution failed.</p>
<div class="refsect3">
<a name="exo-execute-terminal-shell-on-screen.parameters"></a><h4>Parameters</h4>
<div class="informaltable"><table class="informaltable" width="100%" border="0">
<colgroup>
<col width="150px" class="parameters_name">
<col class="parameters_description">
<col width="200px" class="parameters_annotations">
</colgroup>
<tbody>
<tr>
<td class="parameter_name"><p>command_line</p></td>
<td class="parameter_description"><p>shell command line to execute.</p></td>
<td class="parameter_annotations"> </td>
</tr>
<tr>
<td class="parameter_name"><p>working_directory</p></td>
<td class="parameter_description"><p>path to the directory in which to execute <em class="parameter"><code>command_line</code></em>
or <code class="literal">NULL</code> to use the current working directory.</p></td>
<td class="parameter_annotations"> </td>
</tr>
<tr>
<td class="parameter_name"><p>envp</p></td>
<td class="parameter_description"><p>child's environment, or <code class="literal">NULL</code> to inherit parent's.</p></td>
<td class="parameter_annotations"> </td>
</tr>
<tr>
<td class="parameter_name"><p>screen</p></td>
<td class="parameter_description"><p>the <span class="type">GdkScreen</span> on which to run the <em class="parameter"><code>command_line</code></em>
.</p></td>
<td class="parameter_annotations"> </td>
</tr>
<tr>
<td class="parameter_name"><p>error</p></td>
<td class="parameter_description"><p>return location for errors or <code class="literal">NULL</code>.</p></td>
<td class="parameter_annotations"> </td>
</tr>
</tbody>
</table></div>
</div>
<div class="refsect3">
<a name="exo-execute-terminal-shell-on-screen.returns"></a><h4>Returns</h4>
<p> <code class="literal">TRUE</code> on success, else <code class="literal">FALSE</code>.</p>
</div>
<p class="since">Since: <a class="link" href="ch01.html#api-index-0.3.1.3" title="Added in 0.3.1.3">0.3.1.3</a></p>
</div>
</div>
<div class="refsect1">
<a name="exo-Executing-Applications.see-also"></a><h2>See Also</h2>
<p>gtk_show_uri()</p>
</div>
</div>
<div class="footer">
<hr>Generated by GTK-Doc V1.33.1</div>
</body>
</html>